Workflow
This page covers the Agentty interface layout, session lifecycle, session sizes, slash commands, and data location.
For keyboard shortcuts by view, see Keybindings.
Interface Layout🔗
Agentty organizes its interface into four tabs, accessible with Tab:
| Tab | Purpose |
|---|---|
| Sessions | List, create, and manage agent sessions. When a project is active, this tab appears as Sessions (<project-name>). |
| Projects | Select between projects (git repositories) in a split view: Agentty info (ASCII art, version, short description) on top, project table below. |
| Stats | View usage statistics. |
| Settings | Configure Codex reasoning level, default models, and other preferences. |
In session chat view, the status and session title render in a dedicated header row above the output panel.
Session Lifecycle🔗
Session statuses and what you can do in each state:
| Status | Description | Available actions |
|---|---|---|
| New | Session created, prompt not yet sent. | Enter reply, m add to merge queue, r rebase, o open worktree, e open nvim, scroll, help |
| InProgress | Agent is actively working. | o open worktree, e open nvim, scroll, help |
| Review | Agent finished; changes are ready for review. | Enter reply, m add to merge queue, r rebase, o open worktree, e open nvim, d diff, f focused review, Shift+Tab permission mode, scroll, help |
| Question | Agent requested clarification before continuing. | question input mode (Enter submit, Esc skip, text editing keys) |
| Queued | Session is waiting in the merge queue. | read-only view (q, scroll, help) |
| Rebasing | Worktree branch is rebasing onto the base branch. | o open worktree, e open nvim, scroll, help |
| Merging | Changes are being merged into the base branch. | read-only view (q, scroll, help) |
| Done | Session completed and merged. | t toggle summary/output, scroll, help |
| Canceled | Session was canceled by the user. | read-only view (q, scroll, help) |
When Open Commands in Settings contains multiple entries (separated by ||), pressing o opens a selector popup (j/k to move, Enter to open, Esc to cancel).
Typical Transitions🔗
New → InProgress → Review → Done
↘ Canceled
↘ Question → InProgress
↘ Queued → Merging → Done
↘ Rebasing → ReviewWhile a session is InProgress, Agentty keeps the Thinking... status badge for streamed activity. Assistant content streams live when available; if assistant content already streamed, Agentty skips duplicate final-answer append at turn completion.
When the first prompt is submitted for a new session, Agentty stores that prompt as the initial title and starts one background title-generation task using the configured Default Fast Model. That generation runs only once for session initiation; Agentty does not continuously refresh titles.
Clarification Interaction Loop🔗
If an agent emits structured question messages, the session moves to Question status. You answer each question in sequence (or press Esc to skip with no answer), and Agentty sends one consolidated follow-up message back to the same session before returning it to normal execution.
Session Sizes🔗
Agentty classifies sessions by the number of changed lines in their diff:
| Size | Changed Lines |
|---|---|
| XS | 0-10 |
| S | 11-30 |
| M | 31-80 |
| L | 81-200 |
| XL | 201-500 |
| XXL | 501+ |
Session size is recalculated after each completed agent turn and persisted to the session record.
Slash Commands🔗
Type these in the prompt input to access special actions:
| Command | Description |
|---|---|
/model | Switch the model for the current session. |
/stats | Show token usage statistics for the session. |
Data Location🔗
Agentty stores its data in ~/.agentty/ by default. This includes the SQLite database, session logs, and worktree checkouts (under ~/.agentty/wt/).
You can override this location by setting the AGENTTY_ROOT environment variable:
# Run agentty with a custom root directory
AGENTTY_ROOT=/tmp/agentty-test agentty